package com.sun.module_home.net

import com.sun.module_base.network.NetworkApi
import com.sun.module_common.config.BASE_URL
import com.sun.module_common.model.Article
import com.sun.module_home.model.BannerBean
import com.sun.module_common.model.ListWrapper
import com.sun.module_network.HttpResult
import retrofit2.http.GET
import retrofit2.http.Path

/**
 * ApiService 是一个用于网络请求的接口，提供了获取各类文章、问答和Banner数据的功能。
 * 该接口封装了与服务器交互的API调用，使用Retrofit框架实现网络请求。
 *
 * 核心功能包括：
 * - 获取置顶文章列表
 * - 获取分页文章列表
 * - 获取问答列表
 * - 获取首页文章列表
 * - 获取Banner数据
 *
 * 使用示例：
 * ```kotlin
 * val apiService = ApiService.getInstance()
 * val topArticles = apiService.getTopArticle()
 * val articleList = apiService.getArticleList(1)
 * ```
 *
 * 构造函数参数说明：
 * - getInstance()方法无需参数，返回ApiService实例
 *
 * 注意事项：
 * - 所有方法都是suspend挂起函数，需要在协程或挂起作用域中调用
 * - 返回值均为HttpResult包装类型，需要处理可能的网络错误
 * - BASE_URL常量需要在NetworkApi中定义
 *
 * @author:sunc
 * @time :2025/7/30 15:56
 * @desc: 描述
 */
interface ApiService {
    companion object {
        /**
         * 获取ApiService实例
         * @return 返回ApiService实例
         */
        fun getInstance(): ApiService {
            return NetworkApi.INSTANCE.getApi(ApiService::class.java, BASE_URL)
        }
    }

    /**
     * 获取置顶文章列表
     * @return 返回HttpResult包装的置顶文章列表
     */
    @GET("/article/top/json")
    suspend fun getTopArticle(): HttpResult<MutableList<Article>?>

    /**
     * 获取分页文章列表
     * @param page 页码，从1开始
     * @return 返回HttpResult包装的分页文章列表
     */
    @GET("/article/list/{page}/json")
    suspend fun getArticleList(@Path("page") page: Int): HttpResult<ListWrapper<Article>?>

    /**
     * 获取问答列表
     * @param page 页码，从1开始
     * @return 返回HttpResult包装的问答列表
     */
    @GET("/wenda/list/{page}/json")
    suspend fun getWendaList(@Path("page") page: Int): HttpResult<ListWrapper<Article>?>

    /**
     * 获取首页文章列表
     * @param page 页码，从1开始
     * @return 返回HttpResult包装的首页文章列表
     */
    @GET("/user_article/list/{page}/json")
    suspend fun getIndexList(@Path("page") page: Int): HttpResult<ListWrapper<Article>?>

    /**
     * 获取Banner数据
     * @return 返回HttpResult包装的Banner列表
     */
    @GET("/banner/json")
    suspend fun getBanners(): HttpResult<MutableList<BannerBean>?>
}